# PixelBuffer

A 1D color vector to support color manipulation of LED strips. All colors are 24bit RGB colors.

The pixel buffer is typically accessed through a [Led](/api/clients/led) client.

```ts
import { Led } from "@devicescript/core"
import "@devicescript/runtime"

const led = new Led()
// highlight-next-line
const pixels = await led.buffer()
```

It can also be allocated using `pixelBuffer`.

```ts
import { PixelBuffer } from "@devicescript/runtime"

// highlight-next-line
const pixels = PixelBuffer.alloc(32)
```

## Usage

### `at`, `setAt`

Indexing functions similar to `Array.at`, they allow to set color of individual LEDs and support negative indices.

```ts skip
const c0 = pixels.at(0)
pixels.setAt(1, c0)
```

### `clear`

Clears all colors to `#000000`.

```ts skip
pixels.clear()
```

### `view`

Creates a aliased range view of the buffer so that you can apply operations on a subset of the colors.

```ts skip
const view = pixels.view(5, 10)
view.clear()
```

### `correctGamma`

Applies gamma correction to compensate LED and eye perception

```ts skip
// highlight-next-line
pixels.correctGamma()
```

### `rotate`

Shifts the colors in the buffer by the given offset. Use a negative offset to shift right.

```ts skip
pixels.rotate(-1)
```

## Helpers

Here are a few helpers built for `PixelBuffer`, but many others could be added!

### `fillSolid`

This helper function assigns the given color to the entire range.

```ts
import { Led } from "@devicescript/core"
import { fillSolid } from "@devicescript/runtime"

const led = new Led()
const pixels = await led.buffer()

// highlight-next-line
fillSolid(pixels, 0x00_ff_00)

await led.show()
```

### `fillRainbow`

Fills the buffer by interpolating the hue of `hsv` colors.

```ts
import { Led } from "@devicescript/core"
import { fillRainbow } from "@devicescript/runtime"

const led = new Led()
const pixels = await led.buffer()

// highlight-next-line
fillRainbow(pixels)

await led.show()
```

By default, the helper interpolates between `0` and `0xff`,
but this can be changed with optional parameters.

### `fillGradient`

Fills with a linear interpolation of two colors across the RGB space.

```ts
import { Led } from "@devicescript/core"
import { fillGradient } from "@devicescript/runtime"

const led = new Led()
const pixels = await led.buffer()

// highlight-next-line
fillGradient(pixels, 0x00_ff_00, 0x00_00_ff, { circular: true })

await led.show()
```

### `fillPalette`

Fills by interpolating the colors of a palette.

```ts
import { Led } from "@devicescript/core"
import { Palette } from "@devicescript/graphics"
import { fillPalette } from "@devicescript/runtime"

const led = new Led()
const pixels = await led.buffer()
const palette = Palette.arcade()

// highlight-next-line
fillPalette(pixels, palette)

await led.show()
```

### `fillBarGraph`

A tiny bar chart engine to render on a value on a LED strip

```ts
import { Led } from "@devicescript/core"
import { fillBarGraph } from "@devicescript/runtime"

const led = new Led()
const pixels = await led.buffer()

const current = 25
const max = 100

// highlight-next-line
fillBarGraph(pixels, current, max)

await led.show()
```
